home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 432_01 / wf120 / wildfile.doc < prev    next >
Text File  |  1992-01-06  |  15KB  |  387 lines
  1.  
  2.  
  3.                        WildFile for MS-DOS systems
  4.  
  5.                  A *IX SH style file globber written in C
  6.                    V1.20 Dedicated to the Public Domain
  7.  
  8.                                January 07, 1992
  9.                                  J. Kercheval
  10.                          [72450,3702] -- johnk@wrq.com
  11.  
  12.  
  13.  
  14. 01-07-92
  15.  
  16. This is V1.20 of Wildfile.
  17.  
  18. Thanks to F. C. Smith for a bug fix when expanding paths of the form
  19. c:* rather than the fully qualified c:\*.  This version also utilizes
  20. the generic match code from MATCH V1.20 with appropriate ifdef's for
  21. use with the MSDOS path follow character.
  22.  
  23.                                 jbk
  24.  
  25.  
  26. 05-13-91
  27.  
  28. This is V1.14 of Wildfile.
  29.  
  30. Thanks to David Kirschbaum of Toad Hall for adding support for Turbo C
  31. V2.0.
  32.  
  33.                                 jbk
  34.  
  35.  
  36. 05-07-91
  37.  
  38. This is V1.13 of Wildfile, a *IX SH style file Globber.
  39.  
  40. The purpose of this code is to enable the programmer to allow *real*
  41. wildcard file specification.  The UNIX (*IX) SH style wildcard system
  42. has been around for decades and there is absolutely no good reason for
  43. it's lack of presence within MS/PC DOS and its associated tools.
  44.  
  45. I submit this without copyright and with the clear understanding that
  46. this code may be used by anyone, for any reason, with any modifications
  47. and without any guarantees, warrantee or statements of usability of any
  48. sort.
  49.  
  50.  
  51.                                 jbk
  52.  
  53.  
  54.  
  55. *IX SH style wildcard file globbing
  56. ===================================
  57.  
  58. The unix style of wildcard globbing (matching files to a wildcard
  59. specification) is quite a bit more flexible than the standard
  60. approach seen on the MS\PC DOS machines.  The full power of *IX SH
  61. style regular expressions are allowed to specify a file name.  For
  62. instance:
  63.     "*t*"           would match to the filenames test.doc, wet.goo,
  64.                     itsy.bib, foo.tic, etc.
  65.     "th?[a-eg]."    would match to any file without an extension,
  66.                     whose first two letters were "th", with any third
  67.                     letter and whose last letter was a,b,c,d,e or g.
  68.                     (ie. thug, thod, thud, etc.)
  69.     "*"             would match all filenames.
  70.  
  71. The regular expression syntax is described in detail in the source
  72. code and below.
  73.  
  74.  
  75. Implementation
  76. ==============
  77.  
  78. The implementation of the wildcard package is similar in type to the
  79. standard MS/PC DOS function calls for file searches.  There is a
  80. find_firstfile call which begins a search initially and a
  81. find_nextfile call which continues a previous search.  This approach
  82. will normally yield a very quick port from existing *standard*
  83. implementations of wildcard file searching.
  84.  
  85. The include file WILDFILE.H does a good job of describing the
  86. specifics required here.
  87.  
  88.  
  89. WD
  90. ==
  91.  
  92. WD is a very quick implementation of a directory lister to try to
  93. show the usage of the wildfile module as intended.  The program is a
  94. fully functional program complete with usage messages and command
  95. line argument parsing.
  96.  
  97.  
  98. Languages
  99. =========
  100.  
  101. WILDFILE (and its associated module MATCH) were developed and
  102. compiled using both MicroSoft C V6.00A and Borland C++.
  103.  
  104.  
  105.  
  106. ============================================================================
  107.  
  108. ============================================================================
  109.  
  110.  
  111.  
  112. MATCH120
  113.  
  114.  
  115.  
  116.  
  117.                     REGEX Globber (Wild Card Matching)
  118.  
  119.                A *IX SH style pattern matcher written in C
  120.                    V1.20 Dedicated to the Public Domain
  121.  
  122.                                January 07, 1992
  123.                                  J. Kercheval
  124.                          [72450,3702] -- johnk@wrq.com
  125.  
  126.  
  127.  
  128. 01-07-91
  129.  
  130. This is V1.2 of REGEX Globber.
  131.  
  132. To clarify code I have added defines for the standard characters used
  133. within a match pattern and have reformatted the source code.  There
  134. is an internal define to allow this code to be used in filename
  135. regular expression globbing for the MSDOS platform.  This consisted
  136. of disabling the use of the literal escape outside of a range so that
  137. path follows (ie '\') would be handled correctly.
  138.  
  139.                                 jbk
  140.  
  141. 03-12-91
  142.  
  143. This is V1.1 of REGEX Globber.
  144.  
  145.  
  146. 03-12-91
  147.  
  148. I have made a few changes to the match module which do several
  149. things.  The first change is an increase in bad pattern detection
  150. during a match.  It was possible, in some very unlikely cases, to
  151. cook up a pattern which should result in an early bad match but which
  152. would actually cause problems for the parser.  In particular, the
  153. subcase where the literal escape '\' within an open [..] construct at
  154. the end of a pattern would end up with incorrect results.  I
  155. proceeded to create some of these patterns, added them to my test
  156. battery and dove straight in.
  157.  
  158. In the interim I came across a posting to CompuServe (SMATCH by Stan
  159. Aderman) which attempted to create a completely non-recursive
  160. implementation of match (I am not sure this is possible without
  161. explicitly creating your own stack or it's equivalent, like a binary
  162. tree :-{ ).  While the code could not correctly handle multiple '*'
  163. characters in the pattern, there was a few interesting ideas in the
  164. posting.  On some occasions, running match over and over would be
  165. counter productive, especially and in particular when you have a bad
  166. pattern.  I have added a fast routine, is_valid_pattern(), to
  167. determine if the current pattern is well formed which should address
  168. this situation.
  169.  
  170. One other idea which I unceremoniously lifted from SMATCH was (in
  171. hindsight a pretty obvious feature) the return of a meaningful error
  172. code from both the pattern validity routine and from match() (which I
  173. renamed to matche()).
  174.  
  175. I also took some time to experiment with some ways to cut some time
  176. off the routine.  Since this is a SH pattern matcher whose intent is
  177. primarily for shell functions, the changes could not be algorithmic
  178. changes which relied on speedup over large input.  The differences in
  179. execution time were not very significant, but I did manage to gain
  180. approximately 5%-10% speedup when I removed the literal escape ('\')
  181. parsing and pattern error checking.  For those of you who want to use
  182. this for filename wildcard usage, I would recommend doing this since
  183. you should use is_valid_pattern and is_pattern before going out and
  184. finding filenames and the dos path delimiter defaults to the
  185. character used for the literal escape ('\') anyway (Note: I will be
  186. soon be releasing a *IX style file parser in the FINDFILE, FINDNEXT
  187. flavor soon to a Public Domain archive near you :-) ).
  188.  
  189. I also briefly toyed with adding a non-SH regex character '+' to this
  190. module but removed it again.  It was a performance hit of a few
  191. percent and would be mostly unused in any event.  For those
  192. interested in such a feature, the changes are truly minimal.  The
  193. required extra work is: 
  194.  
  195.    1) One case statement each in is_pattern() and is_valid_pattern() 
  196.    2) One case statement in matche()
  197.    3) One addition to a while conditional in matche_after_star()
  198.    4) One addition to an if conditional in matche_after_star()
  199.  
  200. Hint:  The case statements are all "case '+'" and the conditionals
  201.        have "|| *p == '+' " added to them.
  202.  
  203. I have also included a file (MATCH.DOC) which describes matches use and
  204. background as well as a little about regular expressions.
  205.  
  206.                                 jbk
  207.  
  208. 02-24-91
  209.  
  210. This is V1.01 of REGEX Globber.
  211.  
  212.  
  213. 02-22-91 Seattle, WA
  214.  
  215. Hmm. Choke. (Foot in mouth). After griping about buggy routines and
  216. literally seconds after posting this code the first time,  I received
  217. a wonderful new test evaluation tool which allows you to perform
  218. coverage analysis during testing.  Sure enough I found that about
  219. 25% of the paths in the program were never traversed in my current
  220. test battery.  After swallowing my (overly large) pride and coming
  221. up with a test battery which covered the entire path of the program
  222. I found a couple of minor logic bugs involving literal escapes (\)
  223. within other patterns (ie [..] and * sequences).  I have repackaged
  224. these routines and incl